home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 25 / Cream of the Crop 25.iso / os2 / srefv12i.zip / sreflogs.doc < prev    next >
Text File  |  1997-03-23  |  14KB  |  328 lines
  1. 05 Mar 1997:  Configuring the SRE-Filter Common-Log Audit File
  2.  
  3. A) Introduction
  4.  
  5. In keeping with http server standards, SRE-Filter will maintain a
  6. common-log format audit file.
  7.  
  8. Besides offering a compact synopsis, a number of tools exist to help you
  9. analyze common-log files. Furthermore, as an adjunct to the common-log audit
  10. file, SRE-Filter can also record the browser used by each request (as
  11. well as the referer) in seperate log files.
  12.  
  13. This document discusses how to modify the SREFLOGS.INI file.  SREFLOGS.INI
  14. contains the configuration options for these three log files. These
  15. options include the host-specific (and port-specfic)  filenames for
  16. these log files, audit-suppression instructions, and a few display options.
  17.  
  18. At this moment, there is no SRE-Filter configurator for SREFLOGS.INI --
  19. you'll have to use your favorite text editor.  Also note that, as
  20. with most other SRE-Filter configuration files, you can change it
  21. on the fly (SRE-Filter checks SREFLOGS.INI about every 20 seconds).
  22.  
  23.  
  24. -------------------------------------------------
  25. B) Basic configuration
  26.  
  27. A few basic points:
  28.   i) If you want to record information to these audit files, you need to
  29.      enable the WRITE_LOGS parameter (you can use the configurator to do this).
  30.  
  31.  ii) If you are running a single-host server on port 80, and you
  32.      are happy to record all requests in a standard fashion, then you can
  33.      use the default version of SREFLOGS.INI.
  34.  
  35.      If you choose to do this, three files in the DATA\ directory
  36.      of the GoServe "working directory" (say, D:\GOSERVE\DATA)
  37.      will be created (and written to):
  38.         * COMMON.LOG -- the common-log audit file
  39.         * BROWSERS.LOG -- list of browsers
  40.         * REFERER.LOG -- list of referers
  41.  
  42. iii) If post-filter processing has been suppressed (say, with the SEL-specific
  43.      NO_POSTFILTER permission), the request will not be recorded to these
  44.      audit files.
  45.  
  46.  iv) Advanced options: SRE-Filter will "lazy write" the audit files (about
  47.      once a minute).  SRE-Filter will also warn you (via the PMPRINTF
  48.      window) when a log file gets large (greater then 1M).  You can
  49.      change these limits by editing the POSTFCHK.RXX file.
  50.  
  51. -------------------------------------------------
  52. C) Configuration options
  53.  
  54. Configuration is accomplished by setting variables in SREFLOGS.INI.
  55. The following lists the variables, with details below:
  56.  
  57. COMMONLOG           == Default common-log file
  58. COMMONLOG.nnn       == Common-log file for port nnn server.
  59. COMMONLOG.hostn     == Common-log file for the "hostn" host.
  60. COMMONLOG.hostn.nnn == Common-log file for the "hostn" host on port nnn.
  61.  
  62. BROWSERLOG           == Default browser log file
  63. BROWSERLOG.nnn       == Browser log file for port nnn server.
  64. BROWSERLOG.hostn     == Browser log file for the "hostn" host.
  65. BROWSERLOG.hostn.nnn == Browser log file for the "hostn" host on port nnn.
  66.  
  67. REFERERLOG           == Default referer log file
  68. REFERERLOG.nnn       == Referer log file for port nnn server.
  69. REFERERLOG.hostn     == Referer log file for the "hostn" host.
  70. REFERERLOG.hostn.nnn == Referer log file for the "hostn" host on port nnn.
  71.  
  72. NOOPTIONS            == Do not record the portion of the request selector
  73.                         following the ?
  74.  
  75. NOHTTP               == Do not record the HTTP/1.0 portion of the request
  76.                         string
  77.  
  78. NOCODES              == List of "return codes" to not record.
  79.  
  80. NOUSER               == List of IP addresses, and SRE-Filter "usernames", to
  81.                         not record
  82.  
  83. NOREFERER           == List of IP addresse to not record in REFERER.LOG
  84.                            (COMMON and BROWSER logs do NOT pay attention to 
  85.                             this parameter).
  86.  
  87.  
  88.  
  89. NOURL.1              == Stem variable of request selectors to not record
  90. NORUL.2
  91. ..
  92.  
  93. C.1) Configuration Details: COMMONGLOG, BROWSERLOG and REFERERLOG ----
  94.  
  95. The COMMONLOG, BROWSERLOG, and REFERERLOG "stem" variables all have the same
  96. structure. The basic notion is that SRE-Filter will take the server port, and
  97. the server's host nickname, and attempt to find matching COMMONLOG (and
  98. BROWSERLOG and REFERERLOG) variables.  If a match is not found, the "default"
  99. variables are used.
  100.  
  101. You should set these stem variable to equal filenames. If you use a
  102. relative file name (i.e.; FOO.BAR or DIR1/FOO.BAR), the file is
  103. assumed to be relative to the DATA\ subdirectory of the GoServe
  104. working directory.
  105.  
  106. Some examples should help.  These examples use COMMONLOG,
  107. but the logic is exactly the same for BROWSERLOG and REFERERLOG.
  108.  
  109. For these examples, assume the following entries in SREFLOGS.INI
  110. (also assume that the DATA\ subdirectory is D:\GOSERVE\DATA)
  111.  COMMONLOG='COMMON.LOG'
  112.  COMMONLOG.CIRCUS.8080='CIRCUS\COMMON.8080'
  113.  COMMONLOG.ZOO='D:\CIRCUS\WWW\COMMON.LOG'
  114.  
  115. Example 1: if the server is a single host (no host nicknames specified)
  116. on the standard port (80), then SRE-Filter would look for:
  117.    COMMONLOG.80         -- this is the first variable looked for
  118.    COMMONLOG            -- the default
  119. Since COMMONLOG.80 was not specified, COMMONLOG is used (which yields a
  120. value of D:\GOSERVE\DATA\COMMON.LOG).
  121. Note that this example also applies to non-standard ports on single
  122. host systems (with the .80 changed appropriately).
  123.  
  124. Example 2: port 80, host nickname of ZOO:
  125.    COMMONLOG.ZOO.80    -- this is the first variable looked for
  126.    COMMONLOG.ZOO       -- this is the second variable looked for
  127.    COMMONLOG           -- this is the default
  128. COMMONLOG.ZOO.80  was not specified, but COMMONLOG.ZOO was. Thus,
  129. the value will be D:\CIRCUS\WWW\COMMON.LOG.
  130.  
  131. Example 3: port 8080, "host nickname" of CIRCUS:
  132.    COMMONLOG.CIRCUS.8080   -- this is the first variable looked for
  133.    COMMONLOG.CIRCUS        -- this is the second variable looked for
  134.    COMMONLOG               -- this is the default
  135. Since COMMONLOG.CIRCUS.8080 exists; so the value will be
  136. D:\GOSERVE\DATA\CIRCUS\COMMON.8080  (D: must be an HPFS drive).
  137.  
  138. If the desired default is to not record, set COMMONLOG=0.  Note that
  139. you can override this default on a host-nickname/port specific basis.
  140.  
  141. As stated above, the BROWSERLOG and REFERERLOG variables are treated the
  142. same way. Thus, to suppress the REFERERLOG, set REFERLOG=0 (and have
  143. no other REFERERLOG. variables).
  144.  
  145. C.2) The NOxxx options  --------------------------------------
  146.  
  147. The followings options allow you to modify the output to the common-log file,
  148. and to suppress the recording of selected requests.
  149.  
  150. NOOPTIONS:
  151.   If NOOPTIONS=1, then the portion of the request selector following a ?
  152.   will not be included.  Since this can be quite long (as when you are
  153.   using the GET method in an HTML FORM), inclusion of this information can
  154.   lead to very long (and hard to read) entries.
  155.   For example: given a request for: /LOOK1?arg1=sub1/&arg2=1&argx=1&xmac=0
  156.                if NOOPTIONS=1, the "request" portion of the common-log (and
  157.                referers log) will be /LOOK1
  158.  
  159. NOHTTP
  160.   Technically, a request string should end with the HTTP version.
  161.   Since this is almost always HTTP/1.0, and since it's not clear that
  162.   the common-log format requires this information, you can suppress this
  163.   portion of the request string by setting NOHTTP=1.
  164.  
  165. NOCODES
  166.    NOCODES should contain a space delimited list of  3 digit
  167.    "return status codes" that you do NOT want to record. For example,
  168.    you may not be interested in requests that generated a "authorization
  169.    response" (a 401 response). If so, set:
  170.        NOCODES='401 '
  171.    If you are also uninterested in "moved" responses, you can set:
  172.        NOCODES='401 301 302 '
  173.    And if you are sort of perverse, and are not interested in normal
  174.    responses, you can set:
  175.        NOCODES='200 '
  176.  
  177.    If a request selector matches one of these NOCODES, then none of the log
  178.    files are written to.
  179.  
  180.  
  181. NOUSER
  182.    This should contain a space delimited list of IP names (or numeric
  183.    addresses for those clients with no IP name) that you do NOT wish to record.
  184.    It can also contain "usernames" (from SRE-Filter's USERS.IN
  185.    usename/password database).
  186.    That is, requests from these addresses (and from these "users") will NOT be
  187.    recorded.  One sensible use of this is to include OWNER's IP address
  188.    (since you probably don't care about requests you make to yourself), as
  189.    well as the "usernames" of the various SUPERUSERs.
  190.    Note that if you take this suggestion, you must put in the OWNER's IP
  191.    name (in contrast, the SRE-Filter OWNERS variable expects a numeric
  192.    IP address).
  193.  
  194.    Example: NOUSER=' joe.bars.net *.wah.com 151.121.55.6  ADMINX '
  195.  
  196.    Notes:
  197.      * you can use * as a wildcard for a field. Thus, ab.wah.com
  198.        and cd.wah.com would both match *.wah.com, but www.ef.wah.com would
  199.        NOT.
  200.     * If 151.121.55.6 has an IP name of jill.money.gov,
  201.       she would NOT match 151.121.55.6 -- 151.121.55.6 would only match
  202.       if there was NO ip name available.
  203.     * ADMINX is a possible "username" (possibly of a SUPERUSER).
  204.     * If a match to any of these NOCODES occurs, then none of the log files
  205.       are written to.
  206.  
  207. NOREFERER
  208.    This should contain a space delimited list of IP names (or numeric
  209.    addresses for those clients with no IP name) that you do NOT wish to record
  210.    in the REFERER.LOG file.
  211.    That is, requests that were refered from these addresses will NOT be
  212.    recorded in REFERER.LOG.  However, these requests WILL be recorded in the 
  213.    common.log and browser.log files.
  214.  
  215.  
  216.    Example: NOREFERER=' *.my.site.net  backup.site.org '
  217.  
  218.    Notes:
  219.      * you can use * as a wildcard for a field. Thus, ab.wah.com
  220.        and cd.wah.com would both match *.wah.com, but www.ef.wah.com would
  221.        NOT.
  222.     * If 151.121.55.6 has an IP name of jill.money.gov,
  223.       she would NOT match 151.121.55.6 -- 151.121.55.6 would only match
  224.       if there was NO ip name available.
  225.  
  226.  
  227.  
  228.  
  229. NOURL.1
  230. ..
  231. NOURL.n
  232.    The NOURL. entries should contain URLs to NOT record. That is, if a request
  233.    selector matches one of these URLs, it will NOT be recorded.
  234.    For example:
  235.         NOURL.1 = 'IMGS/*
  236.         NOURL.2 = 'BORING/TEDIOUS.HTM '
  237.  
  238.    Notes:
  239.     *  You can include * as a wildcard. Thus, IMGS/HORSE.GIF
  240.        matches NOURL.1, and such requests would NOT be recorded
  241.        the common-log, etc. audit files.
  242.     *  These entries are NOT sensitive to host or port -- all
  243.        NOURL entries will apply to all hosts and ports (perhaps
  244.        we'll fix this up if there's enough demand).
  245.     *  If a request selector matches one of these NOURL. variables, then none
  246.        of the log files are written to.
  247.     *  The several SRE-Filter hit suppresion options (such as
  248.        HIT_OWNER_SUPPRESS, have NO effect on these audit files).
  249.     *  \ are converted to /, and leading / are stripped.
  250.  
  251.  
  252. -------------------------------------------------
  253. D) Structure of .LOG files
  254.  
  255.  
  256. i) The common-log file format -------------------
  257.  
  258. (the following description is adapted from
  259.   http://www.apache.org/docs/mod/mod_log_common.html)
  260.  
  261. The common-log file contains a separate line for each request.
  262. A line is composed of several items (tokens) separated by spaces:
  263.      host ident authuser date request status bytes
  264. If a token does not have a value then it is represented by a hyphen (-).
  265.  
  266. The meanings and values of these tokens are as follows:
  267.  
  268. client
  269.   The fully-qualified domain name of the client, or its IP number if the
  270.   name is not available.
  271. ident
  272.    The identd identity information: NOT SUPPORTED BY SRE-FILTER.
  273. authuser
  274.    The client's username, as provided in the AUTHORIZATION request header.
  275.    Note that the common-log standard suggests that "if the request was for a
  276.    password protected document, then this is the userid used in the request".
  277.    However, SRE-Filter will always include the authuser (if available), even
  278.    if the particular request did not require authorization.
  279. date
  280.    The date and time of the request, in the following format:
  281.       date = [day/month/year:hour:minute:second zone]
  282.    where:
  283.          day = 2 digit
  284.          month = 3 letter
  285.          year = 4 digit
  286.          hour = 2 digit
  287.          minute = 2 digit
  288.          second = 2 digit
  289.          zone = (`+' | `-') 4 digit
  290. request
  291.      The request line from the client, enclosed in double quotes
  292. status
  293.    The three digit status code returned to the client.
  294. bytes
  295.    The number of bytes in the object returned to the client, not including
  296.    any headers.
  297.  
  298. For example:
  299.  acl.wear.org - - [18/Mar/1996:16:24:08 -0500] "GET /SMP/HLO.HTM HTTP/1.0" 200 1251
  300.  
  301. In the above example, the HTTP/1.0 substring may not be standard (you can
  302. suppress it by setting the NOHTTP option in SREFLOGS.INI). Also note that
  303. -0500 corresponds to the EST offset from GMT.
  304.  
  305. ii) The BROWSERS log file ---------------------
  306.  
  307. The browsers log file has the following structure:
  308.    [date] client : user-agent
  309. For example:
  310.   [24/Feb/1997:18:14:30 -0500] 151.121.65.143 : IBM-WebExplorer-DLL/v1.1b
  311.  
  312. iii) The REFERERS log file ----------------------
  313.  
  314. The referers log file has the following structure:
  315.    [date]  "sel"  referer_url
  316. Where SEL is from the request string, and the referer_url is from the
  317. REFERER request header.
  318. For example:
  319.    [24/Feb/1997:18:18:19 -0500] "/SAMPLES/samp1.htm" http://dh.ag.gov/i.htm
  320. (http://dh.ag.gov/i.htm contained a link to /samples/samp1.htm)
  321.  
  322. Note: if a request does not have a REFERER request header (for example, WebEx
  323. does not provide a REFERER request header), an entry will NOT be added to the
  324. REFERERS log.
  325.  
  326.  
  327. -- End of documentation.
  328.